home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3c / getnameinfo.z / getnameinfo
Encoding:
Text File  |  2002-10-03  |  13.1 KB  |  265 lines
  1.  
  2.  
  3.  
  4. GGGGEEEETTTTNNNNAAAAMMMMEEEEIIIINNNNFFFFOOOO((((3333))))                                                  GGGGEEEETTTTNNNNAAAAMMMMEEEEIIIINNNNFFFFOOOO((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ggggeeeettttnnnnaaaammmmeeeeiiiinnnnffffoooo - address-to-nodename translation in a protocol-independent
  10.      manner.
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ttttyyyyppppeeeessss....hhhh>>>>
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ssssoooocccckkkkeeeetttt....hhhh>>>>
  15.      ####iiiinnnncccclllluuuuddddeeee <<<<nnnneeeettttddddbbbb....hhhh>>>>
  16.  
  17.      iiiinnnntttt ggggeeeettttnnnnaaaammmmeeeeiiiinnnnffffoooo ((((ccccoooonnnnsssstttt ssssttttrrrruuuucccctttt ssssoooocccckkkkaaaaddddddddrrrr ****ssssaaaa,,,,
  18.                          ssssoooocccckkkklllleeeennnn____tttt ssssaaaalllleeeennnn,,,,
  19.                          cccchhhhaaaarrrr ****nnnnooooddddeeee,,,, ssssoooocccckkkklllleeeennnn____tttt nnnnooooddddeeeelllleeeennnn,,,,
  20.                          cccchhhhaaaarrrr ****sssseeeerrrrvvvv,,,, ssssoooocccckkkklllleeeennnn____tttt sssseeeerrrrvvvvlllleeeennnn,,,,
  21.                          uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt ffffllllaaaaggggssss))))
  22.  
  23. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  24.      The ggggeeeettttnnnnaaaammmmeeeeiiiinnnnffffoooo function is defined for protocol-independent
  25.      address-to-nodename translation.  Its functionality is a reverse
  26.      conversion of ggggeeeettttaaaaddddddddrrrriiiinnnnffffoooo((((3333)))),,,, and implements such functionality by
  27.      calling ggggeeeetttthhhhoooossssttttbbbbyyyyaaaaddddddddrrrr((((3333NNNN)))) and ggggeeeettttsssseeeerrrrvvvvbbbbyyyyppppoooorrrrtttt((((3333NNNN)))),,,, in a more sophisticated
  28.      manner.
  29.  
  30.      This function looks up an IP address and port number provided by the
  31.      caller in the DNS and system-specific database, and returns text strings
  32.      for both in buffers provided by the caller.  The function indicates
  33.      successful completion by a zero return value; a non-zero return value
  34.      indicates failure.
  35.  
  36.      The first argument, _s_a, points to either a ssssoooocccckkkkaaaaddddddddrrrr____iiiinnnn structure (for
  37.      IPv4) or a ssssoooocccckkkkaaaaddddddddrrrr____iiiinnnn6666 structure (for IPv6) that holds the IP address
  38.      and port number. The _s_a_l_e_n argument gives the length of the ssssoooocccckkkkaaaaddddddddrrrr____iiiinnnn
  39.      or ssssoooocccckkkkaaaaddddddddrrrr____iiiinnnn6666 structure.
  40.  
  41.      If the socket address structure contains IPv6 unspecified address ("::"),
  42.      a lookup is not performed, and the [EAI_NONAME] error is returned.
  43.  
  44.      If the argument _n_o_d_e is non-NULL and the argument _n_o_d_e_l_e_n is nonzero,
  45.      then the argument _n_o_d_e points to a buffer able to contain up to _n_o_d_e_l_e_n
  46.      characters that will receive the node name as a null-terminated string.
  47.      If the argument _n_o_d_e is NULL or the argument _n_o_d_e_l_e_n is zero, the node
  48.      name will not be returned.  If the node's name cannot be located, the
  49.      numeric form of the node's address is returned instead of its name.
  50.  
  51.      If the argument _s_e_r_v is non-NULL and the argument _s_e_r_v_l_e_n is nonzero,
  52.      then the argument _s_e_r_v points to a buffer able to contain up to _s_e_r_v_l_e_n
  53.      characters that will receive the service name as a null-terminated
  54.      string.  If the argument _s_e_r_v is NULL or the argument _s_e_r_v_l_e_n is zero,
  55.      the service name will not be returned.  If the service name cannot be
  56.      located, the numeric form of the service address (for example, its port
  57.      number) is returned instead of its name.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. GGGGEEEETTTTNNNNAAAAMMMMEEEEIIIINNNNFFFFOOOO((((3333))))                                                  GGGGEEEETTTTNNNNAAAAMMMMEEEEIIIINNNNFFFFOOOO((((3333))))
  71.  
  72.  
  73.  
  74.      Unfortunately most systems do not provide constants that specify the
  75.      maximum size of either a fully-qualified domain name or a service name.
  76.      Therefore to aid the application in allocating buffers for these two
  77.      returned strings the following constants are defined in <_n_e_t_d_b._h>:
  78.  
  79.  
  80.           ####ddddeeeeffffiiiinnnneeee NNNNIIII____MMMMAAAAXXXXHHHHOOOOSSSSTTTT  1111000022225555
  81.           ####ddddeeeeffffiiiinnnneeee NNNNIIII____NNNNAAAAXXXXSSSSEEEERRRRVVVV   33332222
  82.  
  83.      The arguments _n_o_d_e and _s_e_r_v cannot both be NULL.
  84.  
  85.      The _f_l_a_g_s argument is a flag that changes the default actions of this
  86.      function.  By default the fully-qualified domain name (FQDN) for the node
  87.      is returned, but
  88.  
  89.           - If the flag bit NI_NOFQDN is set, only the nodename portion of the
  90.           FQDN is returned for local hosts.
  91.  
  92.           - If the flag bit NI_NUMERICHOST is set, the numeric form of the
  93.           node's address is returned instead of its name, under all
  94.           circumstances.
  95.  
  96.           - If the flag bit NI_NAMEREQD is set, an error is returned if the
  97.           node's name cannot be located.
  98.  
  99.           - If the flag bit NI_NUMERICSERV is set, the numeric form of the
  100.           service address is returned (for example, its port number) instead
  101.           of its name, under all circumstances.
  102.  
  103.           - If the flag bit NI_DGRAM is set, this indicates that the service
  104.           is a datagram service (SOCK_DGRAM).  The default behavior is to
  105.           assume that the service is a stream service (SOCK_STREAM).
  106.  
  107.      These  NI_xxx flags are defined in <_n_e_t_d_b._h>.
  108.  
  109.      Function ggggeeeettttnnnnaaaammmmeeeeiiiinnnnffffoooo(((()))) is thread safe.
  110.  
  111. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  112.      The following code tries to get nodename, and service name, for a given
  113.      socket address.
  114.  
  115.  
  116.           #include <stdio.h>
  117.           #include <sys/socket.h>
  118.           #include <netdb.h>
  119.  
  120.           main(){
  121.                  struct addrinfo hints, *res, *res0;
  122.                  int error;
  123.                  int s;
  124.                  const char *cause = NULL;
  125.                  char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. GGGGEEEETTTTNNNNAAAAMMMMEEEEIIIINNNNFFFFOOOO((((3333))))                                                  GGGGEEEETTTTNNNNAAAAMMMMEEEEIIIINNNNFFFFOOOO((((3333))))
  137.  
  138.  
  139.  
  140.  
  141.                  memset(&hints, 0, sizeof(hints));
  142.                  hints.ai_family = AF_UNSPEC;
  143.                  hints.ai_socktype = SOCK_STREAM;
  144.                  error = getaddrinfo("www.company.example", "ftp",
  145.                                    &hints, &res0);
  146.                  if(error){
  147.                          fprintf(stderr, "%s", gai_strerror(error));
  148.                          exit(1);
  149.                     }
  150.                     s = -1;
  151.                     for (res = res0; res; res = res->ai_next) {
  152.                          s = socket(res->ai_family, res->ai_socktype,
  153.                                    res->ai_protocol);
  154.                          if (s < 0) {
  155.                               cause = "Error: socket";
  156.                               continue;
  157.                          }
  158.                          if(connect(s, res->ai_addr, res->ai_addrlen) < 0 ) {
  159.                               cause = "Error: connect";
  160.                               close(s);
  161.                               s = -1;
  162.                               continue;
  163.                          }
  164.                          cause = "Success";
  165.                          if(res->ai_family == AF_INET6){
  166.                            inet_ntop(AF_INET6,
  167.                                 &(((struct sockaddr_in6 *)res->ai_addr)->sin6_addr),
  168.                                 hbuf, sizeof(hbuf));
  169.                          } else
  170.                          if(res->ai_family == AF_INET){
  171.                            inet_ntop(AF_INET,
  172.                                 &(((struct sockaddr_in *)res->ai_addr)->sin_addr),
  173.                                 hbuf, sizeof(hbuf));
  174.                          }
  175.                          printf("Getaddrinfo: Address = %s  ", hbuf);
  176.                          bzero(hbuf, sizeof(hbuf));
  177.                          if (getnameinfo(res->ai_addr, res->ai_addrlen,
  178.                                   hbuf, sizeof(hbuf),
  179.                                   sbuf, sizeof(sbuf),
  180.                                   NI_NAMEREQD)) {
  181.                                fprintf(stderr, "could not resolve hostname");
  182.                                exit(1);
  183.                          }
  184.                          printf("Getnameinfo: host = %s, serv = %s  ", hbuf, sbuf);
  185.                       close(s);
  186.                          break; /*okay we got one*/
  187.                     }
  188.                     fprintf(stderr, cause);
  189.                  freeaddrinfo(res0);
  190.           }
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. GGGGEEEETTTTNNNNAAAAMMMMEEEEIIIINNNNFFFFOOOO((((3333))))                                                  GGGGEEEETTTTNNNNAAAAMMMMEEEEIIIINNNNFFFFOOOO((((3333))))
  203.  
  204.  
  205.  
  206. FFFFIIIILLLLEEEESSSS
  207.      ////eeeettttcccc////hhhhoooossssttttssss
  208.      ////eeeettttcccc////iiiippppnnnnooooddddeeeessss
  209.      ////eeeettttcccc////rrrreeeessssoooollllvvvv....ccccoooonnnnffff
  210.  
  211. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  212.      The function indicates successful completion by a zero return value; a
  213.      non-zero return value indicates failure. Error codes are as below:
  214.  
  215.      EAI_AGAIN      The name could not be resolved at this time.
  216.                     Future attempts may succeed.
  217.      EAI_BADFLAGS   The flags had an invalid value.
  218.      EAI_FAIL       A non-recoverable error occurred.
  219.      EAI_FAMILY     The address family was not recognized or the address
  220.                     length is invalid for the specified family.
  221.      EAI_MEMORY     There was a memory allocation failure.
  222.      EAI_NONAME     The name does not resolve for the supplied parameters.
  223.                     NI_NAMEREQD is set and the node's name cannot be located,
  224.                     or both nodename and servname were null.
  225.      EAI_OVERFLOW   Argument buffer overflowed.
  226.      EAI_SYSTEM     A system error occurred. The error code can be found in
  227.                     errno.
  228.  
  229. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  230.      ggggeeeettttaaaaddddddddrrrriiiinnnnffffoooo((((3333)))),,,, ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyyaaaaddddddddrrrr((((3333)))),,,, ggggeeeetttthhhhoooossssttttbbbbyyyyaaaaddddddddrrrr((((3333)))),,,, ggggeeeettttsssseeeerrrrvvvvbbbbyyyyppppoooorrrrtttt((((3333)))),,,,
  231.      ggggeeeettttsssseeeerrrrvvvvbbbbyyyynnnnaaaammmmeeee((((3333)))),,,, iiiinnnneeeetttt____nnnnttttoooopppp((((3333)))),,,, hhhhoooossssttttssss((((5555)))),,,, sssseeeerrrrvvvviiiicccceeeessss((((5555))))....
  232.  
  233. SSSSTTTTAAAANNNNDDDDAAAARRRRDDDDSSSS
  234.      The ggggeeeettttnnnnaaaammmmeeeeiiiinnnnffffoooo(((()))) function is defined in IEEE POSIX 1003.1g draft
  235.      specification, draft-ietf-ipngwg-rfc2553bis-03.txt, and documented in
  236.      "Basic Socket Interface Extensions for IPv6" (RFC2553).
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.